Authentication On-Premises

Authentication On-Premises is similar to the Authentication Workflow but is used when your organization's Data Retention policies (See Data Settings) specify that end user credentials must be deleted after some period of time. As with the Authentication Workflow, when someone claiming to be an end userClosed A person who is a customer, patient, constituent, or client of a Jumio customer, and who participates in the “customer journey” as part of their interaction with the Jumio customer. you have already onboarded returns to your platform, a fresh Selfie and Facemap are captured and compared to an existing Facemap. However, since the original Facemap generated by the onboarding process may have been deleted from Jumio's servers, you must upload the existing Facemap that will be used for the comparison. In this case you must have downloaded and stored the Facemap that was acquired as part of the end user onboarding before it was deleted. You can then upload the stored Facemap and use it with the Authentication On-Premises workflow.

Retrieve the Onboarding Facemap

After the end user has successfully onboarded, but before the credentials are deleted in accordance with your Data Retention policies, you can download the Facemap and store it for future use with Authentication On-Premises.

Important! Your tenant must be configured to allow downloading a Facemap. Contact Jumio Support to make sure that the Allow download of facemap option is enabled.

When Allow download of facemap is enabled the Workflow Details response from the on-boarding workflow includes the URL you can use to retrieve the Facemap as a single binary file. See also: GET parts API.

Download and store the Facemap file, along with the account ID so they can be accessed as needed for subsequent a uthentications.

Example FACEMAP href

   "credentials": [
      {
         ...
      },
      {
         "id": "4915434a-9b0f-4bbf-b088-dfea00b4b680",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/FACEMAP"
            },

...

Update the Account to Initiate an Authentication On-Premises Transaction

Use the PUT request for the Accounts API to update the existing end user account. The account ID value saved from the on-boarding transaction is used as a path parameter in the request URL.

In the request body, specify workflow key 10071 to use the standard Authorization On-Premises workflow.

Workflow 10071 uses the Authentication capability to compare a newly-acquired Facemap to a Facemap you upload using the API. If you require a custom workflow with additional services or risk signals contact your Jumio representative.

The response body will include three credential objects:

  • A FACEMAP that will have allowed channels for WEB and SDK. This is the new FACEMAP that will be generated as part of the WEB or SDK customer journey.

  • A FACEMAP with the API allowed channel, and an api:parts:facemap URL you can use to upload the stored FACEMAP.

  • A SELFIE that will have allowed channels for WEB and SDK. This is the new SELFIE that will be generated as part of the WEB or SDK customer journey.

Example Request Body

{
   "customerInternalReference":"MyCompany",
   "workflowDefinition":{
     "key": 10071
  }
}

Example Response Credentials

{
...
   "workflowExecution": {
      "id": "078e9c6b-e2d9-4c41-8c28-627106387d31",
      "credentials": [
         {
            "id": "ab05065f-f8f0-4892-a34e-47dfbf1c5689",
            "category": "FACEMAP",
            "allowedChannels": [
               "WEB",
               "SDK"
            ]
         },
         {
            "id": "eda8ebae-8c84-4fa0-8f9d-6538e907e04f",
            "category": "FACEMAP",
            "allowedChannels": [
               "API"
            ],
            "api": {
               "token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAA_5XOMQ7CMAxA0btkxpLjOI7DxsjKDRInYWkBiUogIe5Oi7gA69cb_sv152Fxe-dFvUaRQIHI7VwxO7a1UxS1JAhYYgUumKBWG9BS4R6txUpj41-MSXs2qdCpZWBjD2qkIJQ8StDUgl_xY_R_uJ36WPXtel_mcoHlOp_ByjRtm79JGYwYFTxjBCZpUIUbBOOiOY9uUd37Azm5chvsAAAA.We0X_lp4xFxKS8C4nz5nY5y13R9UJvm4uaobVof5o8qCV4eBA-bXmPkSiEAaqRNGAnXfp5fdZSgz5zxIJUprzg",
               "parts": {
                  "facemap": "https://api.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/078e9c6b-e2d9-4c41-8c28-627106387d31/credentials/eda8ebae-8c84-4fa0-8f9d-6538e907e04f/parts/FACEMAP"
               },
               "workflowExecution": "https://api.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/078e9c6b-e2d9-4c41-8c28-627106387d31"
            }
         },
         {
            "id": "5888b4ce-59fe-43e4-bd00-c9bc582798f7",
            "category": "SELFIE",
            "allowedChannels": [
               "WEB",
               "SDK"
            ]
         }
      ]
   }
}

Upload the Stored Facemap

After the account is updated but before the customer journey is initiated, upload the stored Facemap using a POST request with the api:parts:facemap URL in the response to the account update.

Do not make the call to finalize the workflow after uploading the Facemap. Instead, once the Facemap is successfully uploaded, initiate the customer journey as you would with any other WEB Client or SDK workflow.

Retrieve the Decision

If your integration has integrated a Callback service it will be notified when the transaction is complete. Alternatively you can call the Transaction Status API to determine if the transaction has been PROCESSED.

Once the transaction has completed you can call the Workflow Details API to retrieve the decision and other workflow data.

Example Details Response

{
   "workflow": {
      "id": "334179b3-196f-4a11-a7bf-f3d5e9e4ec4f",
      "status": "PROCESSED",
      "definitionKey": "10071",
      "customerInternalReference": "MyCompany"
   },
   "account": {
      "id": "2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f"
   },
   "createdAt": "2023-04-27T21:17:44.771Z",
   "startedAt": "2023-04-27T21:20:22.086Z",
   "completedAt": "2023-04-27T21:20:22.915Z",
   "credentials": [
      {
         "id": "7b9f5a06-76bf-483c-ab9c-041fc3cff2c6",
         "category": "SELFIE",
         "parts": [
            {
               "classifier": "FACE",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/7b9f5a06-76bf-483c-ab9c-041fc3cff2c6/parts/FACE"
            }
         ]
      },
      {
         "id": "63fb3a15-fdea-472c-9b81-6771f26df043",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP"
            },
            {
               "classifier": "LIVENESS_1",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_1"
            },
            {
               "classifier": "LIVENESS_3",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_3"
            },
            {
               "classifier": "LIVENESS_2",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_2"
            },
            {
               "classifier": "LIVENESS_5",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_5"
            },
            {
               "classifier": "LIVENESS_4",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_4"
            },
            {
               "classifier": "LIVENESS_6",
               "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/LIVENESS_6"
            }
         ]
      },
      {
         "id": "d1a3e2c9-539f-487e-9937-62bd11f6a07b",
         "category": "FACEMAP",
         "parts": [
            {
               "classifier": "FACEMAP"
            }
         ]
      }
   ],
   "decision": {
      "type": "PASSED",
      "details": {
         "label": "PASSED"
      },
      "risk": {
         "score": 0.0
      }
   },
   "steps": {
      "href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/334179b3-196f-4a11-a7bf-f3d5e9e4ec4f/steps"
   },
   "capabilities": {
      "usability": [
         {
            "id": "da066373-6aff-4fdb-a63b-84b933b02740",
            "credentials": [
               {
                  "id": "d1a3e2c9-539f-487e-9937-62bd11f6a07b",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         },
         {
            "id": "92439dde-dda6-4789-b398-be28c8c2c2e8",
            "credentials": [
               {
                  "id": "7b9f5a06-76bf-483c-ab9c-041fc3cff2c6",
                  "category": "SELFIE"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         },
         {
            "id": "d057ab3c-7b84-46f8-8c5f-8248147367ba",
            "credentials": [
               {
                  "id": "63fb3a15-fdea-472c-9b81-6771f26df043",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            }
         }
      ],
      "authentication": [
         {
            "id": "08772b5b-a443-4eb6-964b-47705ac631ac",
            "validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/63fb3a15-fdea-472c-9b81-6771f26df043/parts/FACEMAP",
            "credentials": [
               {
                  "id": "63fb3a15-fdea-472c-9b81-6771f26df043",
                  "category": "FACEMAP"
               }
            ],
            "decision": {
               "type": "PASSED",
               "details": {
                  "label": "OK"
               }
            },
            "data": {
               "type": "IPROOV_STANDARD"
            }
         }
      ]
   }
}